home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 42 / Amiga Format AFCD42 (Issue 126, Aug 1999).iso / -serious- / programming / other / ioblixdevkit / autodocs / ioblix.doc next >
Text File  |  1999-05-14  |  18KB  |  475 lines
  1.  
  2. TABLE OF CONTENTS
  3.  
  4. ioblix.resource/--background--
  5. ioblix.resource/AddIRQHook
  6. ioblix.resource/AllocChipList
  7. ioblix.resource/FindChip
  8. ioblix.resource/FreeChipList
  9. ioblix.resource/ObtainChip
  10. ioblix.resource/ObtainChipShared
  11. ioblix.resource/ReleaseChip
  12. ioblix.resource/ReleaseChipShared
  13. ioblix.resource/RemIRQHook
  14.  
  15. ioblix.resource/--background--                   ioblix.resource/--background--
  16.  
  17.    PURPOSE
  18.       The ioblix.resource is created by SetupIOBlix during startup and provides
  19.       several functions to gain exclusive as well as shared access to any chip
  20.       the IOBlix multi I/O boards provide. If you ever want to use one of the
  21.       IOBlix chips you should ALWAYS use either ObtainChip() or
  22.       ObtainChipShared() to prevent other ioblix.resource-conform programs from
  23.       interferring with your program. All device drivers being delivered with
  24.       your IOBlix board follow this rule. And hopefully all third-party drivers
  25.       will also do.
  26.       To access these functions just call OpenResource(IOBLIXRESNAME) and use
  27.       the returned pointer in the same manner as library bases are used.
  28.  
  29.  
  30. ioblix.resource/AddIRQHook                           ioblix.resource/AddIRQHook
  31.  
  32.    NAME
  33.       AddIRQHook  - add a private interrupt function to the IOBlix interrupt
  34.                     chain
  35.  
  36.    SYNOPSIS
  37.       void = AddIRQHook( node )
  38.                          A0
  39.  
  40.       void AddIRQHook( struct IRQHookNode * );
  41.  
  42.    FUNCTION
  43.       Adds the given node to the IOBlix interrupt chain. This is necessary
  44.       because normal interrupt handling by AmigaOS will loose some interrupts on
  45.       heavy system load.
  46.       Just imagine two applications using the IOBlix board (eg one serial and
  47.       one parallel port). When adding your own interrupt function with Exec's
  48.       AddIntServer() the system will just recognize the first of two
  49.       simultaneously happening interrupts, because the first function will return
  50.       a successfull interrupt handling and Exec will cease any further handling
  51.       within its chain. But at this time the second interrupt has still not been
  52.       processed. IOBlix' own interrupt chain avoids this problem by checking all
  53.       active chips before returning control to Exec.
  54.       The function given in ihn_HookFunc will be passed the data given in
  55.       ihn_HookUserData on the stack. Just as Exec's interrupt handling functions
  56.       a return value of 0 indicates that no interrupt has happened. Any other
  57.       return value indicates a successfull interrupt handling.
  58.  
  59.    INPUTS
  60.       node     -- a correctly initialized IRQHookNode
  61.  
  62.    EXAMPLE
  63.       /* add a private interrupt function */
  64.       ULONG __saveds myIRQFunc( APTR userData);
  65.       APTR myUserData;
  66.       struct IRQHookNode *node;
  67.  
  68.       if (IOBlixBase = OpenResource(IOBLIXRESNAME)) {
  69.         node->ihn_Node.ln_Name = "TestHook";
  70.         node->ihn_Node.ln_Pri = 5; /* priority within the chain */
  71.         node->ihn_HookFunc = myIRQFunc;
  72.         node->ihn_HookUserData = myUserData;
  73.         AddIRQHook(node);
  74.         /* do whatever you want */
  75.         RemIRQHook(node);
  76.       }
  77.  
  78.       ULONG myIRQFunc( APTR userData )
  79.       {
  80.         /* check wether an interrupt has happened or not                   */
  81.         /* if yes, then do all necessary things and return a value of != 0 */
  82.         /* else just return 0                                              */
  83.       }
  84.  
  85.    SEE ALSO
  86.       RemIRQHook
  87.  
  88. ioblix.resource/AllocChipList                     ioblix.resource/AllocChipList
  89.  
  90.    NAME
  91.       AllocChipList -- get a list of all available chips
  92.  
  93.    SYNOPSIS
  94.       list = AllocChipList( void )
  95.       D0
  96.  
  97.       struct List *AllocChipList( void );
  98.  
  99.    FUNCTION
  100.       This function returns a copy of the internal list of all available chips.
  101.       You are allowed to iterate through the list, but you must not change
  102.       anything. All nodes in the list are of type (struct IOBlixChipNode *). No
  103.       chip in the list is obtained in a ObtainChip()-like manner.
  104.  
  105.    RESULTS
  106.       chipNode -- a list of all available chips, or NULL if the call failed
  107.  
  108.    EXAMPLE
  109.       /* print information about all IOBlix chips in the system */
  110.       struct IOBlixResource *IOBlixBase;
  111.       struct List *list;
  112.       struct IOBlixChipNode *node;
  113.  
  114.       if (IOBlixBase = OpenResource(IOBLIXRESNAME)) {
  115.         if (list = AllocChipList()) {
  116.           node = (struct IOBlixChipNode *)chipList->lh_Head;
  117.           while (node->icn_Node.ln_Succ) {
  118.             switch (node->icn_Type) {
  119.               case ICT_Z2_SERIAL_CHIP:
  120.                 printf("IOBlix Z2 UART, %s, %ld bytes FIFO\n",
  121.                        node->icn_Description, node->icns_FIFOSize);
  122.                 break;
  123.               case ICT_Z2_PARALLEL_CHIP:
  124.                 printf("IOBlix Z2 parallel port, %s, %ld bytes FIFO\n",
  125.                        node->icn_Description, node->icnp_FIFOSize);
  126.                 break;
  127.               default:
  128.                 break;
  129.               printf("chip is in use by %s\n",
  130.                      (node->icn_Owner) ? node->icn_Owner : "nobody");
  131.             }
  132.             node = (struct IOBlixChipNode *)node->icn_Node.ln_Succ);
  133.           }
  134.           FreeChipList(list);
  135.         } else {
  136.           printf("failed to allocate chip list\n");
  137.         }
  138.       }
  139.  
  140.    SEE ALSO
  141.       FreeChipList
  142.  
  143. ioblix.resource/FindChip                               ioblix.resource/FindChip
  144.  
  145.    NAME
  146.       FindChip -- find a chip in the resource's database
  147.  
  148.    SYNOPSIS
  149.       chipNode = FindChip(chipType, chipNum)
  150.       D0                  D0        D1
  151.  
  152.       struct IOBlixChipNode *FindChip( ULONG, ULONG );
  153.  
  154.    FUNCTION
  155.       This function searches the internal list for the chip matching the given
  156.       values for chip type and number. If the search is successfull the chip's
  157.       information block is returned, but the chip is NOT obtained!
  158.       You may use this function just to check if a certian chip is available
  159.       and to get some information about it. All fields in IOBlixChipNode are
  160.       considered READ-ONLY, you must not change anything.
  161.  
  162.    INPUTS
  163.       chipType -- the type of chip you want to find
  164.       chipNum  -- internal number of the chip you want to find
  165.                   valid range is 0..IOBLIX_Z2_NUM_SERUNITS for UARTs
  166.                                  0..IOBLIX_Z2_NUM_PARUNITS for parallel ports
  167.                                  0..IOBLIX_Z2_NUM_FIFOUNITS for external FIFOs
  168.                   to obtain a chip on multiple IOBlix boards use
  169.                   boardNum*10+chipNum as value, ie 13 is the third UART on the
  170.                   second board
  171.  
  172.    RESULTS
  173.       chipNode -- a pointer to the chip's information block, or NULL if the
  174.                   chip is not available.
  175.  
  176.    EXAMPLE
  177.       /* try to find serial unit 0 on first IOBlix board */
  178.       struct IOBlixResource *IOBlixBase;
  179.       struct IOBlixChipNode *chipInfo;
  180.  
  181.       if (IOBlixBase = OpenResource(IOBLIXRESNAME)) {
  182.         if (chipInfo = FindChip(ICT_Z2_SERIAL_CHIP, 0)) {
  183.           /* chip is available, let's see what it is able to do */
  184.           printf("UART is a %s with %ld bytes FIFO"\n,
  185.                  chipInfo->icn_Description, chipInfo->icns_FIFOSize);
  186.           printf("UART is in use by %s\n",
  187.                  (chipInfo->icn_Owner) ? chipInfo->icn_Owner : "nobody");
  188.         } else {
  189.           printf("serial port #0 is not available\n");
  190.         }
  191.       }
  192.  
  193.    SEE ALSO
  194.       ReleaseChip, FindChip
  195.  
  196. ioblix.resource/FreeChipList                       ioblix.resource/FreeChipList
  197.  
  198.    NAME
  199.       FreeChipList -- free a previously allocated chip list
  200.  
  201.    SYNOPSIS
  202.       void = FreeChipList( list )
  203.                            A0
  204.  
  205.       void FreeChipList( struct List * );
  206.  
  207.    FUNCTION
  208.       This function frees the given list again.
  209.  
  210.    INPUTS
  211.       list     -- a list previously allocated by AllocChipList(). Passing NULL
  212.                   is a no-op.
  213.  
  214.    SEE ALSO
  215.       AllocChipList
  216.  
  217. ioblix.resource/ObtainChip                           ioblix.resource/ObtainChip
  218.  
  219.    NAME
  220.       ObtainChip -- obtain a chip for exclusive use
  221.  
  222.    SYNOPSIS
  223.       chipNode = ObtainChip(chipType, chipNum, newOwner, oldOwner)
  224.       D0                    D0        D1          A0        A1
  225.  
  226.       struct IOBlixChipN